Skip Headers

Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# OCI Flush or Refresh Functions

This section describes the OCI flush or refresh functions.

Table 17-5 Flush or Refresh Functions

Function/Page | Purpose
--- | ---
OCICacheFlush() | Flush modified persistent objects in cache to server
OCICacheRefresh() | Refresh pinned persistent objects
OCIObjectFlush() | Flush a modified persistent object to the server
OCIObjectRefresh() | Refresh a persistent object

## OCICacheFlush()

Purpose

Flushes modified persistent objects to the server

Syntax

    sword OCICacheFlush ( OCIEnv              *env,
                          OCIError            *err,
                          CONST OCISvcCtx     *svc,
                          dvoid               *context,
                          OCIRef              *(*get)
                                              ( dvoid   *context,
                                                ub1     *last ),
                          OCIRef              **ref );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

svc (IN)

  OCI service context.

context (IN) [optional]

  Specifies a user context that is an argument to the client callback function `get`. This parameter is set to `NULL` if there is no user context.

get (IN) [optional]

  A client-defined function which acts an iterator to retrieve a batch of dirty objects that need to be flushed. If the function is not `NULL`, this function will be called to get a reference of a dirty object. This is repeated until a `NULL` reference is returned by the client function or the parameter `last` is set to `TRUE`. The parameter `context` is passed to `get()` for each invocation of the client function. This parameter should be `NULL` if user callback is not given. If the object that is returned by the client function is not a dirtied persistent object, the object is ignored.

  All the objects that are returned from the client function must be newed or pinned using the same service context, otherwise an error is signalled. Note that the cache flushes the returned objects in the order in which they were marked dirty.

  If this parameter is passed as `NULL` (for example, no client-defined function is provided), then all dirty persistent objects for the given service context are flushed in the order in which they were dirtied.

ref (OUT) [optional]

  If there is an error in flushing the objects (`*ref`) will point to the object that is causing the error. If `ref` is `NULL`, then the object will not be returned. If `*ref` is `NULL`, then a reference will be allocated and set to point to the object. If `*ref` is not `NULL`, then the reference of the object is copied into the given space. If the error is not caused by any of the dirtied object, the given `REF` is initialized to be a `NULL` reference (`OCIRefIsNull(*ref`) is `TRUE`).

  The `REF` is allocated for session duration (`OCI_DURATION_SESSION`). The application can free the allocated `REF` using the `OCIObjectFree()` function.

Comments

This function flushes the modified persistent objects from the object cache to the server. The objects are flushed in the order that they are newed or marked updated or deleted.

See Also: "OCIObjectFlush()"

This function incurs at most one network round trip.

Related Functions

OCIObjectFlush()

## OCICacheRefresh()

Purpose

Refreshes all pinned persistent objects in the cache.

Syntax

    sword OCICacheRefresh ( OCIEnv            *env,
                           OCIError           *err,
                           CONST OCISvcCtx    *svc,
                           OCIRefreshOpt      option,
                           dvoid              *context,
                           OCIRef             *(*get)(dvoid *context),
                           OCIRef             **ref );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

svc (IN)

  OCI service context.

option (IN) [optional]

  If `OCI_REFRESH_LOADED` is specified, all objects that are loaded within the transaction are refreshed. If the option is `OCI_REFRESH_LOADED` and the parameter `get` is not `NULL`, this function will ignore the parameter.

context (IN) [optional]

  Specifies a user context that is an argument to the client callback function `get`. This parameter is set to `NULL` if there is no user context.

get (IN) [optional]

  A client-defined function which acts an iterator to retrieve a batch of objects that need to be refreshed. If the function is not `NULL`, this function will be called to get a reference of an object. If the reference is not `NULL`, then the object will be refreshed. These steps are repeated until a `NULL` reference is returned by this function. The parameter `context` is passed to `get()` for each invocation of the client function. This parameter should be `NULL` if user callback is not given.

ref (OUT) [optional]

  If there is an error in refreshing the objects, (`*ref`) will point to the object that is causing the error. If `ref` is `NULL`, then the object will not be returned. If `*ref` is `NULL`, then a reference will be allocated and set to point to the object. If `*ref` is not `NULL`, then the reference of the object is copied into the given space. If the error is not caused by any of the object, the given ref is initialized to be a `NULL` reference (`OCIRefIsNull(*ref`) is `TRUE`).

Comments

This function refreshes all pinned persistent objects and all unpinned persistent objects are freed from the object cache.

See Also: For more information about refreshing, see the description of OCIObjectRefresh(), and the section "Refreshing an Object Copy".

Caution: When objects are refreshed, the secondary-level memory of those objects could potentially move to a different place in memory. As a result, any pointers to attributes which were saved prior to this call may be invalidated. Examples of attributes using secondary-level memory include `OCIString *`, `OCIColl *`, and `OCIRaw *`.

Related Functions

OCIObjectRefresh()

## OCIObjectFlush()

Purpose

Flushes a modified persistent object to the server.

Syntax

    sword OCIObjectFlush ( OCIEnv        *env,
                           OCIError      *err,
                           dvoid         *object );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the descriptions of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

object (IN)

  A pointer to the persistent object. The object must be pinned before this call.

Comments

This function flushes a modified persistent object to the server. An exclusive lock is obtained implicitly for the object when it is flushed. When the object is written to the server, triggers may be fired. This function returns an error for transient objects and values, and for unmodified persistent objects.

Objects can be modified by triggers at the server. To keep objects in the cache consistent with the database, an application can free or refresh objects in the cache.

If the object to flush contains an internal LOB attribute and the LOB attribute was modified due to an `OCIObjectCopy()`, `OCILobAssign()`, or `OCILobLocatorAssign()` or by assigning another LOB locator to it, then the flush makes a copy of the LOB value that existed in the source LOB at the time of the assignment or copy of the internal LOB locator or object.

See Also: For more information on LOB functions, see"LOB Functions" .

Related Functions

OCIObjectPin(), OCICacheFlush()

## OCIObjectRefresh()

Purpose

Refreshes a persistent object from the most current database snapshot.

Syntax

    sword OCIObjectRefresh ( OCIEnv        *env,
                             OCIError      *err,
                             dvoid         *object );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

object (IN)

  A pointer to the persistent object, which must already be pinned.

Comments

This function refreshes an object with data retrieved from the latest snapshot in the server. An object should be refreshed when the objects in the object cache are inconsistent with the objects at the server.

Note: When an object is flushed to the server, triggers can be fired to modify more objects in the server. The same objects (modified by the triggers) in the object cache become out-of-date, and must be refreshed before they can be locked or flushed. This occurs when the user issues a SQL statement or PL/SQL procedure to modify any object in the server.

Caution: Modifications made to objects (dirty objects) since the last flush are lost if unmarked objects are refreshed by this function.

The various meta-attribute flags and durations of an object are modified after being refreshed:

Table 17-6 Object Status After Refresh

Object Attribute | Status After Refresh
--- | ---
existent | set to appropriate value
pinned | unchanged
allocation duration | unchanged
pin duration | unchanged

The object that is refreshed will be replaced-in-place. When an object is replaced-in-place, the top-level memory of the object will be reused so that new data can be loaded into the same memory address. The top level memory of the `NULL` indicator structure is also reused. Unlike the top-level memory chunk, the secondary memory chunks will be freed and reallocated.

You should be careful when writing functionality that holds on to a pointer to the secondary memory chunk, such as assigning the address of a secondary memory to a local variable, because this pointer can become invalid after the object is refreshed.

This function does nothing for transient objects or values.

Related Functions

OCICacheRefresh()